.Dd January 18, 2022
.Dt PLATYPUS 1
.Os Darwin
.Sh NAME
.Nm platypus
.Nd create a macOS application bundle from a command line script.
.Sh SYNOPSIS
.Nm
.Op OPTIONS
.Ar scriptPath
.Ar [destinationPath]
.Sh DESCRIPTION
.Nm
is the command line counterpart to the Platypus Mac application.
It creates a macOS application bundle from a command line script.
See https://sveinbjorn.org/platypus for details.
.Pp
.Nm
defaults to creating application bundles, but can also create Platypus profiles
that are loadable by both the command line program and the Platypus application.
.Pp
If the scriptPath parameter is '-', script text is read from standard input.
.Pp
The following option flags are supported (parsed in the order in which they
are passed):
.Bl -tag -width -Fl
.It Fl O, -generate-profile
Create a profile document instead of creating an application bundle. When this
option is enabled, the "destinationPath" paramater (i.e. the final argument to
the program) should have a .platypus suffix. If the string '-' is provided
as destination path, the profile property list XML will be dumped to STDOUT.
.It Fl P, -load-profile Ar profilePath
Loads all settings from a Platypus profile document. It is still necessary to
specify a destination path for the application. Subsequent arguments can
override profile settings.
.It Fl a, -name Ar appName
Specifies the name of the application.  This is can be different from the name
of the .app bundle itself, and is displayed in the application's menus, "About"
window and Info.plist property list.
.It Fl o, -interface-type Ar interfaceType
Specifies the application's interface type, which should be one of
the following:
.Pp
.Ar 'None'
The application does not display any user interface except for Dock icon & menu.
.Pp
.Ar 'Progress Bar'
The application displays a progress bar while running.
.Pp
.Ar 'Text Window'
The application displays a window with a text field with all script output.
.Pp
.Ar 'Web View'
The application displays a window with a web view which renders script output
as HTML.
.Pp
.Ar 'Status Menu'
The application displays a status menu item in the menubar which runs the
script and displays its output when clicked.
.Pp
.Ar 'Droplet'
The application displays a droplet window for dropping files on for processing
by the script.
.Pp
The default interface type is 'Text Window'.
.It Fl i, -app-icon Ar iconPath
Specifies a file to use as the icon for the application bundle. The file must
be an Apple .icns file. If not specified, the default Platypus app icon will
be used. If specified, but left empty (''), no application icon will be set
for the app.
.It Fl Q, -document-icon Ar iconPath
Specifies a file to use as icon for the application's documents. Must be an
Apple .icns file.
.It Fl p, -interpreter Ar interpreterPath
Sets script interpreter (e.g. /usr/bin/python or /bin/sh). If the interpreter
is not specified, the command line tool will try to guess the correct
interpreter. If this fails, the default shell interpreter /bin/sh is used.
.It Fl V, -app-version Ar version
Sets the application bundle's version. This is displayed in the Info.plist
property list and About window.
.It Fl u, -author Ar authorName
Sets the name of the application author (e.g. "Apple Computer" or "John Smith").
If not specified, this defaults to the current user's full user name.
.It Fl f, -bundled-file Ar filePath
Specifies a file to be bundled with the application. The file will be copied
over to the Resources folder of the application bundle, which is the same
folder in which the script runs. Any number of files can be bundled in this
way.
.It Fl I, -bundle-identifier Ar bundleIdentifier
Sets the application's bundle identifier. An application identifier is a
reverse DNS name (e.g. com.apple.iTunes) that uniquely identifies the
application. If this option is left empty, it will default to an identifier
of the format "org.username.appname" (e.g. org.sveinbjorn.Platypus).
.It Fl A, -admin-privileges
This flag makes the application request administrator privileges via Apple's
Security Framework (i.e. prompt for a password) and then executes the script
with those privileges. For details on the nature of these privileges, see the
Apple documentation for the AuthorizationExecuteWithPrivileges() in
Security.framework. This is not strictly equivalent to running as root.
.It Fl D, -droppable
Makes the application droppable, i.e. capable of receiving dragged and dropped
files as arguments to the script. The application bundle's property list is
modified so that it can receive dropped files in the Dock and Finder. These
files are then passed on to the script as arguments.
.It Fl F, -text-droppable
Makes the application text droppable, i.e. makes it accept dragged text
snippets, which are then passed to script via STDIN.
.It Fl N, -service
Makes the app register as a Dynamic Service accessible from the Services
application submenu.
.It Fl B, -background
This option causes the application to run in the background so its icon will
not appear in the Dock.  This is done by registering the application with
LaunchServices as a user interface element (LSUIElement).
.It Fl R, -quit-after-execution
This option makes the application quit once the script has been executed.
.It Fl X, -suffixes Ar suffixes
Only relevant if the application accepts dropped files. This flag specifies
the file suffixes (e.g. .txt, .wav) that the application can open. This should
be a |-separated string (e.g. "txt|wav|jpg").
.It Fl T, -uniform-type-identifiers Ar utis
Only relevant if the application accepts dropped files. This flag specifies
the Uniform Type Identifiers (UTIs) that the application can open.  This should
be a |-separated string (e.g. "public.item|public.folder"). Suffixes are
ignored if this flag is used.
.It Fl U, -uri-schemes Ar schemes
Set application as handler for URI schemes. These can be either standard
URI schemes such as http or custom URI schemes of your choice. See
documentation for details. Multiple items should be a |-separated string
(e.g. "ftp|myscheme|someotherscheme").
.It Fl Z, -file-prompt
Show an Open File dialog when the application launches.
.It Fl G, -interpreter-args Ar arguments
Arguments for the script interpreter.  These should be specified as
a |-separated string (e.g. '-w|-s|-l').
.It Fl C, -script-args Ar arguments
Arguments for the script.  These should be specified as
a |-separated string (e.g. '-w|-s|-l').
.It Fl b, -text-background-color Ar hexColor
Set background color of text (e.g. #ffffff).
.It Fl g, -text-foreground-color Ar hexColor
Set foreground color of text (e.g. #000000).
.It Fl n, -text-font Ar fontName
Set font and font size for text view
(e.g. 'Monaco 10').
.It Fl K, -status-item-kind Ar kind
For Status Menu interface type only.  Set display kind for Status Menu
interface type.  This can be "Text" or "Icon".
.It Fl Y, -status-item-title Ar title
For Status Menu interface type only.  Set the display title for the status
item in Status Menu interface type.
.It Fl L, -status-item-icon Ar imagePath
For Status Menu interface type only.  Set the icon image for the status item
in Status Menu interface type. Must be an image file in one of the formats
supported by the Cocoa APIs (e.g. PNG, JPEG, TIFF etc.)
.It Fl c, -status-item-sysfont
For Status Menu interface type only. Makes menu use system font instead of
user-defined styling.
.It Fl d, -symlink
A symlink to the original script is created inside the application bundle
instead of copying the script over. Symlinks are also created to any
bundled files.
.It Fl l, -optimize-nib
Strip the bundled application nib file to reduce its size. Makes the nib
uneditable. Only works if Apple's Xcode is installed.
.It Fl y, -overwrite
Overwrite any pre-existing files or folders in destination path.
.It Fl v, -version
Print the version of this program
.It Fl h, -help
Print help and usage string
.El
.Pp
Exits 0 on success, and >0 if an error occurs.
.Sh FILES
.Bl -tag -width "/usr/local/share/platypus/PlatypusDefault.icns" -compact
.It Pa /usr/local/bin/platypus
program binary
.It Pa /usr/local/share/platypus/ScriptExec
executable binary
.It Pa /usr/local/share/platypus/MainMenu.nib
nib file for app
.It Pa /usr/local/share/platypus/PlatypusDefault.icns
default icon
.El
.Sh EXAMPLES
platypus -P myProfile.platypus ~/Desktop/MyApplication.app
.Pp
platypus -o 'Text Window' script.pl PerlScript.app
.Pp
platypus -a 'My App' -p /usr/bin/python myPythonScript.py
.Pp
platypus -D -a MyDroplet -o 'Droplet' ~/droplet.sh
.Sh AUTHORS
.An Sveinbjorn Thordarson <sveinbjorn@sveinbjorn.org>
